In some extraordinary cases, it is useful to inject custom bytecode directly in the agent code. This is useful, for example, if you want to do some performance testing and trace the timing of certain method invocations to try to determine where a slowdown in the code is occurring.

Profilers are normally the tools you use to do this; however, when an agent is deployed out in the field or in production, sometimes it is not feasible to install a profiler on the machine or the network where the agent is running. Using Byteman might be the only alternative.

Another use-case which Byteman can be used is to inject code that artificially causes faults in the agent or one of its plugins. This is useful if you want to perform some tests on the fault tolerance and/or error handling of the agent or plugins.

Byteman is a small yet powerful utility that can inject bytecode in an existing application.

The attached tar file allows you to easily install Byteman into your RHQ Agent and install a set of rules without downloading any additional code or setting up additional configuration settings in your RHQ Agent. The zip contains a file (byteman-rules.txt) that has two sample Byteman rules (they trace the amount of time each plugin takes to calculate a resource's availability status). If you want to write your own rules (or were given a set of rules by someone trying to analyze your RHQ environment), just edit that file with the rules you want and restart the agent with the included rhq-agent-with-byteman.sh script. Your rules will get installed into Byteman that runs inside the RHQ Agent.

See the Byteman documentation on how to write your own Byteman rules.

The tar file already contains a version of Byteman for you (version 1.3.0). If you want to use a newer Byteman, then download it from here:

http://www.jboss.org/byteman/downloads.html

and copy the newer byteman.jar over the one that comes with the tar file.

To run the agent with Byteman installed, export the environment variable RHQ_AGENT_HOME and run the rhq-agent-with-byteman.sh script:

> RHQ_AGENT_HOME=/my/rhq/agent/location
> export RHQ_AGENT_HOME
> ./rhq-agent-with-byteman.sh